Skip to content

fix(sessions): Swiftfin AVPlayer gets HDR HEVC as a copy instead of an SDR H.264 transcode - #604

Merged
braedonsaunders merged 2 commits into
braedonsaunders:mainfrom
oleedv:fix/swiftfin-avplayer-hdr-hevc
Nov 20, 2026
Merged

braedonsaunders merged 2 commits into
braedonsaunders:mainfrom
oleedv:fix/swiftfin-avplayer-hdr-hevc

Conversation

@oleedv

@oleedv oleedv commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

Problem

Swiftfin's native player (AVPlayer, tvOS/iOS) never gets HEVC from Ether. An HDR10 or Dolby Vision HEVC MKV is re-encoded to H.264 and tone mapped to SDR, even though the client declares HEVC, HDR10 and Dolby Vision. When the re-encode is avoided, HDR titles still don't play: AVPlayer fetches the master playlist and gives up.

There are two separate causes, one per commit.

1. VideoCodecTag is evaluated against the source container

Swiftfin's AVPlayer profile accepts HEVC only with a required sample entry tag (MediaPlayerType+AVPlayer.swift):

{"Condition": "EqualsAny", "Property": "VideoCodecTag", "Value": "hvc1|dvh1", "IsRequired": true}

profileDeliveryAllowed checks the copied stream's CodecTag from the source. Matroska has no sample entry, so the tag is empty, the required condition fails, and only the H.264 encode passes. The fMP4 segments Ether writes do carry a sample entry: the transcoder tags HEVC hvc1 (dvh1 for a copied DV profile 5 source) and H.264 avc1.

Fix: for an fMP4 decision, profileDeliveryAllowed stamps the output stream with the sample entry the transcoder will write (fmp4VideoTag), so the condition is evaluated against what the client actually receives.

2. The single-variant HLS master has no RESOLUTION or FRAME-RATE

With (1) applied, SDR HEVC copies played, but every PQ copy failed. The traefik access log for a DV 8.1 title shows the pattern each time: master.m3u8 fetched twice, no variant playlist request, Sessions/Playing/Stopped about 3 s later. The same title transcoded to SDR H.264 with the same 38 subtitle renditions played, so only the variant line differed:

#EXT-X-STREAM-INF:BANDWIDTH=15825000,CODECS="hvc1.2.4.L150.90,ec-3",VIDEO-RANGE=PQ,SUPPLEMENTAL-CODECS="dvh1.08.06/db1p",SUBTITLES="subs"

The CODECS / VIDEO-RANGE / SUPPLEMENTAL-CODECS values match Apple's own DV 8.1 example and what Jellyfin sends. What is missing are RESOLUTION and FRAME-RATE, which the HLS authoring spec requires on every video variant (9.2, 9.15). tvOS AVPlayer tolerates their absence for SDR but rejects a PQ / Dolby Vision variant without them. Ether's Plex master already writes both; the sessions master (Jellyfin/Emby/Vela) did not.

Fix: new transcode.HLSVariantGeometry returns RESOLUTION (source size for a copy, decisionOutputSize for an encode) and FRAME-RATE (omitted when unknown, nothing at all when the size is unknown), and Broker.serveMaster adds it to the single-variant line. The ladder path already had both.

Tests

  • TestSwiftfinAVPlayerCopiesHEVCIntoFMP4: with Swiftfin's AVPlayer profile, an HDR10 HEVC MKV is copied into fMP4 (no tone map, no H.264), and a source tagged hev1 is accepted as well. Fails without the first commit.
  • TestHLSVariantGeometry: copy keeps source geometry and ignores a height cap, an encode follows the encoded size, unknown frame rate or size, audio only.

go vet, gofmt and go test ./internal/transcode/ ./internal/sessions/ ./internal/frontends/... pass on Go 1.27.4.

Verified on a device

Applied to v0.3.15 and tested with Swiftfin tvOS (AVPlayer) on Apple TV 4K:

Title Source Before After
Madden (2026) DV 8.1 HEVC MKV, 3840x1600 H.264 SDR transcode; with (1) only: master fetched, playback abandoned HEVC copy, HDR, first frame 1.6 to 5.4 s
The Odyssey (2026) HDR10 HEVC remux MKV H.264 SDR transcode HEVC copy, HDR, first frame 1.8 s
South Park S01E01 SDR HEVC 2160p MKV H.264 transcode HEVC copy, first frame 1.6 s

The master now served for Madden:

#EXT-X-STREAM-INF:BANDWIDTH=15825000,RESOLUTION=3840x1600,FRAME-RATE=24.000,CODECS="hvc1.2.4.L150.90,ec-3",VIDEO-RANGE=PQ,SUPPLEMENTAL-CODECS="dvh1.08.06/db1p",SUBTITLES="subs"

Its init segment has an hvc1 sample entry with hvcC and dvvC, so Dolby Vision is available with the HDR10 base layer as fallback.

Not addressed here: the master still has no AVERAGE-BANDWIDTH (also a MUST in 9.14); AVPlayer did not need it in these tests.

@braedonsaunders

Copy link
Copy Markdown
Owner

Thanks, reviewed and merged into the 0.3.16 branch; it lands on main with the 0.3.16 release candidate (this PR will show as merged then). Evaluating VideoCodecTag against the fMP4 sample entry Ether actually writes is the right fix, and RESOLUTION/FRAME-RATE on the sessions master matches what the Plex master already sends. Thanks for the device table.

@braedonsaunders
braedonsaunders merged commit e81a0e0 into braedonsaunders:main Nov 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants